<html>
<!-- $LastChangedDate: 2009-11-07 22:56:33 -0500 (Sat, 07 Nov 2009) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - Graph Module</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - Graph Module</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#SceneGraph'>SceneGraph</a></li>
  <li><a href='#Graph'>Graph</a></li>
  <li><a href='#Subgraph'>Subgraph</a></li>
  <li><a href='#State-Sorting'>State-Sorting (NodeSort)</a>
  <li><a href='#Visitors'>Visitors</a></li>
  <li><a href='#ModelCache'>ModelCache</a></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview</h2>
<p><!--date-->[2008/02]</p>
<p>
There are 3 levels of graph classes: SceneGraph, Graph, Subgraph.
<br>These are Facade classes that abstract the exact arrangement of nodes.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='SceneGraph'></a>
<h2>SceneGraph</h2>
<p><!--date-->[2009/01]</p>
<pre>
                     +------------+
                     | root node  |
                 +---+------------+--+
                 |        |          |
                 |        |          |
          +--------+  +--------+  +--------+
          | branch |  | branch |  | branch |
          |  node  |  |  node  |  |  node  |
          | default|  |  [1]   |  |  [2]   |
          +--------+  +--------+  +--------+
</pre>
<p>
This arrangement circumvents OSG's rule of allowing child nodes
to override similar state of its parent which wouldn't be restored
after traversal crosses over to a sibling node.
</p>
<p>
The SceneGraph should be partitioned into <i>branches</i>.
<i>Branch nodes </i> are group nodes with different graphical states.
Most 3D Objects can be attached using <code>SceneGraph::AttachNode()</code>
which attach under the branch node having a default state.
Optionally, new special branch nodes can be attached using
code>SceneGraph::AttachBranchNode(GroupNode)</code>
and the client can attach nodes directly to that special branch node.
</p>
<h3>C++ Classes</h3>
<p>
SceneGraph is a singleton that provides the public interface.
<br>SceneGraph _is_ a BaseSceneGraph and _has_ a <a href='ShadowSceneGraph#module_shadows.html'>ShadowSceneGraph</a>.
<br>Some base methods are overridden to fork operations to both.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Graph'></a>
<h2>Graph</h2>
<p><!--date-->[2008/02]</p>
<p>
The Graph class represents a per-Object graph
(ObjectGraph would be its long name).
A Graph is passed as an arg to Object ctor.
Graph is a Facade over the implemented arrangement of OSG nodes.
</p>
<h3>Graph May Have Two Transform Nodes</h3>
<p>
Graph ctor may be passed a transform node as the root node.
However, the Graph class isn't aware of that fact,
Graph ctor always proceeds to create a transform node
and places under it the incoming root node.
This allows, transparently to Graph, correcting the orientation of a 3D model
prior to encapsulating it as a Graph object.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Subgraph'></a>
<h2>Subgraph</h2>
<p><!--date-->[2008/02]</p>
<p>
Subgraph defines a partition of a Graph.
Subgraph is typically used to define parts of an aircraft's 3D model.
Optionally, Subgraph can model a part that has a limited range of movement
such as landing gear.
</p>
<p>
3D model files (.ac) typically name a part of a mesh.
A Visitor is created to searche for a named node in a Graph,
which becomes the root node of a Subgraph.
A transform node is spliced in order to rotate the part.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='State-Sorting'></a>
<a name='NodeSort'></a>
<a name='Scene-Graph Optimization'></a>
<h2>State-Sorting (NodeSort)</h2>
<p><!--date-->[2009/03]</p>
<p>
To keep the scene-graph optimally sorted by state,
the SceneGraph class has a set of <i>branch nodes</i>.
Branch nodes are mapped a <i>NodeSort</i> value
that defines specific graphical states (shader, no fog, etc).
Object classes can override Object::GetNodeSort() to cause
SceneGraph::AttachObject() to place them under the appropriate branch node.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Visitors'></a>
<h2>Visitors</h2>
<p><!--date-->[2007/12]</p>
<p>
The Visitor design pattern is ideal for graphs.
Extended Graph functionality is provided in the form of Visitor classes.
This Visitor pattern keeps Graph class minimal.
Graph can be extended by adding new Visitor classes
(rather than adding new Graph methods or Graph derivatives).
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='ModelCache'></a>
<h2>ModelCache</h2>
<p><!--date-->[2008/02]</p>
<p>
ModelCache caches the results of osgDB::readNodeFile().
Sharing the same node saves enormous amounts of memory.
A shared node has multiple parent nodes.
The reason a 3D model can exist in multiple locations
is because its shared node is placed under separate transform nodes.
</p>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Sat Nov  7 14:50:04 CST 2009
<!-- hhmts end -->
</font>
</p>

</body>
</html>
